This document explains how to work with the view objects derived from the class FW_CControl. It supersedes the section "Adding Controls to your view" starting on page 93 of the ODF Developer's Guide shipped with ODF Release 1. This release supports the basic Macintosh controls, buttons, scroll bars and popup menus. The architecture is in place to add more custom controls in the future and to use the same API to support controls on other platforms. ODF Form is our show-case example for controls, you should read this with the Form project open, ready to browse its source code.
Note on Controls and OpenDoc
Using native Macintosh controls in OpenDoc parts is one area when ODF does a lot of extra work for you, since displaying controls properly in a "non-application world" can be quite challenging. However, we did leave some problems to be solved in future releases, especially with respect to controls that are displayed across multiple facets.
Using ODF Controls
The class hierarchy for ODF 1 control classes is the following:
Controls are small UI objects that respond to user interactions and send notifications to let your part know when to perform appropriate actions. A control derives from FW_CView, it's a lightweight view which cannot contain any subviews. It also inherits from FW__MNotifier in order to send notifications to other objects.
This release implements only the standard controls, i.e. platform native controls. They belong to their own FW_CNativeControl class because they are wrappers to underlying Mac OS controls. A future ODF release will support native controls for other platforms. We will also implement custom controls which don't have an underlying platform equivalent, such as Icon buttons on the Macintosh.
FW_CRadioCluster is not a control class per se but is used in conjunction with radio buttons to manage a group of mutually exclusive buttons.
Adding Controls to Your Frame
When you create a control, you must specify a superview object to be the parentView of the control. The superview can be the frame itself. ODF stores the control in the parent's subviews list and redraws it along with any other subviews.
FW_CControl::FW_CControl(Environment* ev,
FW_CSuperView* parentView,
ODID viewId,
const FW_CRect& bounds,
FW_Message msg,
FW_ControlValue value)
• viewId can be 0 or a number to identify this view within the parent view (it only needs to be unique within the parent's view hierarchy).
• bounds specify the position and size of the control within the parent view.
• msg is what is sent when the control's value changes, or 0 if you are not interested in this event.
• value is the initial value of this control, for instance 1 for a radio button or check-box.
The easiest way to add controls is to define them in resources in the list of your frame's views. You must use a resource type from a derived class because FW_CControl and FW_CNativeControl are abstract classes. For instance the resource definition of a button looks like this:
Control resource types are declared in the file ODF:Framewrk:FWViews:Include:FWViews.fr. See also the file ODF:Framewrk:FWViews:Include:FWViews.k for common constants.
Using Notifications
Because controls are also FW_MNotifier objects they can broadcast messages to other objects when the user interacts with them, usually with a mouse click. For each control you must decide which FW_MReceiver object(s) will be interested in receiving the control's message. The Engineering note "Notification" gives a general description of the notification subsystem and its classes. We will limit this section to what is specific to controls.
In general a control has only 1 receiver, its parent view or the frame itself. The receiver is a custom class, in which you implement a HandleNotification method to respond to this control and maybe others. The easiest way to connect a control to its receiver is by using the constant FW_kViewReceiver or FW_kFrameReceiver in the control resource definition as shown above with the button example. Leave 0 in that field for controls which don't need receivers. If you create the control without using resources, or if you need to define more than 1 receiver, you can use the method LinkControlTo which takes a receiver argument.
Both the receiver resource field and the LinkControlTo method have the effect of creating a FW_CInterest object with the control's message and adding it to the receiver's list of interests, i.e. the following code is executed internally:
The control's message value is the data sent when the control's value changes: this happens either when it is clicked on or when its value is modified by program with SetValue(). ODF controls use the following constants defined in FWNotDef.h:
// Values which can be used in your view resources
const FW_Message FW_kNullMsg = 0;
const FW_Message FW_kButtonPressedMsg = -10; // standard msg for buttons
const FW_Message FW_kDefaultButtonMsg = -12; // reserved for dialogs
const FW_Message FW_kCancelButtonMsg = -13; // reserved for dialogs
const FW_Message FW_kPopupClickedMsg = -20; // standard msg for popups
// Values which cannot be used directly in your view resources
const FW_Message FW_kScrollMsg = -100;
const FW_Message FW_kRadioClusterMsg = -101;
const FW_Message FW_kNotifierDeletedMsg = -102;
In general you are interested in responding to buttons and popup menu selections. You can use the predefined constants FW_kButtonPressedMsg and FW_kPopupClickedMsg or you can define your own message values (use positive numbers to avoid future conflicts with ODF).
The last step is to implement the HandleNotification method in your receiver class. The following listing shows how a class derived from FW_CFrame and FW_MReceiver responds to buttons:
FW_CControl* control = controlNotification.GetControl(ev);
ODID viewId = controlNotification.GetViewId(ev);
...
break;
...
All controls send messages of the type FW_CControlNotification, which carries more information than the base type FW_CNotification. You can safely cast the notification argument and retrieve a pointer to the control itself or its view id. Popup menus and scroll bars can use their own types FW_CPopupMenuNotification and FW_CScrollNotification.
FW_CNativeControl Interface
FW_CNativeControl adds the following methods to its base class FW_CControl:
Disable(), Enabled()
Use Disable to gray out a button and Enable to make it active again. Controls are always enabled by default. If you want a button to be disabled when the frame is created you must call Disable it in your frame's PostCreateViewFromStream method since this attribute is not available in the resource type.
SetLabel(), GetLabel()
These methods allow you to change or read a button's or popup's label. The last parameter of SetLabel should be false only if you are sure that the control doesn't need to be refreshed right away.
GetPlatformControlHandle()
This method returns a handle to the native platform control, you can cast it to ControlHandle on the Macintosh. This may be convenient to retrieve more information about a control however it is not generally possible to change any internal attribute this way without confusing ODF.
Other new methods of FW_CNativeControl don't need to be called directly from your part's code.
Using Buttons (FW_CButton)
Creation by Program or Resource
The class FW_CButton implements the native buttons, push button, radio button and check box. Use the resource type FW_RButton to define a button in resources as shown earlier, or use the class constructor:
FW_CButton(Environment* ev,
FW_CSuperView* container,
ODID viewId,
const FW_CRect& bounds,
FW_ButtonKind kind,
const FW_CString& label,
const FW_CFont& font = FW_kSystemFont12,
FW_Message msg = FW_kButtonPressedMsg,
FW_ControlValue value = 0);
Button view Attributes
You need to define a view id that is unique within the parent view, unless you are not interested in using this view id later to access the button object or handle the button's notifications.
The view binding attribute is initialized to FW_kFixedBounds in order to keep buttons in a fixed position when their parent view is resized. You can change that by calling FW_CView::SetBindings or by using a different initial value in the button resource. Binding constants are defined in ODF:Framewrk:FWViews:Include:FWViews.k
Button Kinds
The possible values for the "kind" argument are: FW_kPushButton, FW_kRadioButton, FW_kCheckButton and FW_kDefaultPushButton. This last kind should be used to create a push button with the standard Macintosh outline indicating that it responds to <Return> and <Enter> keys (you must also use the FW_kDefaultButtonMsg message value at the same time).
GetButtonKind() returns the kind value.
SetButtonKind() can be used to change from FW_kPushButton to FW_kDefaultPushButton, or vice-versa, at runtime.
Button Values
Radio buttons and check boxes can have a control value of 0 or 1 to indicate their state. Use a value of 1 in the button constructor or the button resource to turn the button on. The states of push buttons don't change, their value is always 0.
The methods GetState and SetState are equivalent to FW_CControl methods GetValue and SetValue except that they use boolean arguments.
Changing the value of a radio button or check box makes the button broadcast a notification containing the button's message (unless this message is 0).
Button Messages
In order to respond to a mouse click in a push button you must set its message field to a non-null value, either the predefined constant FW_kButtonPressedMsg or your own value.
The default and cancel buttons of a dialog frame should use the constants FW_kDefaultButtonMsg and FW_kCancelButtonMsg respectively. This makes them respond to certain keys (<Return> or <Enter> for the default button, Command-<period> or <Escape> for the cancel button) as if they were clicked in. In addition, this allows the base class FW_CDialogFrame to dismiss the dialog.
In general you won't need to respond to mouse clicks in radio buttons and check boxes, only the state of these controls is of interest. You should leave the message field set to 0 and also leave the resource's control receiver field null.
Radio Clusters
A group of radio buttons represents a set of mutually exclusive choices. Only one button at a time should be turned on and clicking on another button should turn off the previous selected button. This behavior can be easily implemented by creating an FW_CRadioCluster object for each group of radio buttons.
In resources, use the type FW_RRadioCluster after the list of subviews where the radio buttons are declared. Follow the example of ODF Form (ODF:Form:Sources:Views.fr), right now you need to include the radio cluster(s) in your own superview resource type because of a resource compiler bug:
FW_RRadioCluster
(
1, // Dummy field
{ k14400RadioID, k28800RadioID, kFasterRadioID } // List of radio buttons
),
You can also create the radio cluster by program like this:
fRadioCluster = FW_NEW(FW_CRadioCluster, (ev));
fRadioCluster->AddRadio(ev, radio1);
fRadioCluster->AddRadio(ev, radio2);
fRadioCluster->AddRadio(ev, radio3);
The selected (or "on") button is either the first one added to the cluster or the last one which was created with a value of 1. In general it's easier to list the buttons in the same order as they appear visually and initialize one of them with a value of 1.
Radio cluster objects don't need to be deleted in your frame's destructor. They are deleted automatically when the last button is removed during the destruction of views (this a case where FW_kNotifierDeletedMsg is used).
FW_CRadioCluster::GetButtonOn() returns the currently selected button, FW_CRadioCluster::GetButtonIdOn() returns its view id.
Note: A radio cluster object is not a view, it is purely a receiver which turns buttons on and off. If you need to demarcate a group of radio buttons with a border and a label add a FW_CGroupBox view before the buttons, as it is done in Form.
Using Popup Menus (FW_CPopupMenu)
Creation by Program or Resource
The class FW_CPopupMenu implements native popup menus. To create a popup menu you can either use a resource FW_RPopupMenu or the constructor of FW_CPopupMenu. In the current release you must also create a Mac MENU resource with ResEdit or another tool and add it to your part editor project (in a future release we will support the same ODF menu resources used for the menu bar). See ODF Form for an example using popup menus.
The control value is not used, leave it set to 0. The message and receiver attributes should be left null as well if you are not interested in responding to popup selections, otherwise use the constant FW_kPopupClickedMsg or your own custom message and set the receiver field to the frame or the parent view.
Popup Menu Attributes
This release uses the native Macintosh popup menus and thus relies on the same attributes (see chapter 5 of Inside Macintosh:Macintosh ToolBox Essentials for more information):
• The Mac menu id is the MENU resource built separately with ResEdit or another tool. If you forget to add this resource to your part there won't be any error at the creation of the popup but it will be invisible.
• The title width is the pixel width of the title (do not use fixed coordinates like elsewhere!). You can leave 0 even if you specify a title, in which case the width will be adjusted automatically.
• The initial menu item lets you specify which menu item should be visible first.
• The menu variation can be one of the popup variants defined in the Mac header <controls.h>. In particular you can use popupUseAddResMenu to fill a popup with a list of resources of a certain type, for instance a list of Fonts.
• The menu refCon field can be used in conjunction with a variation of popupUseAddResMenu to specify the resource type, for instance the long value equal to 'FONT'.
• The menu font should be FW_SYSTEM_FONT by default.
• The menu title is not required.
Other Mac popup menu attributes can be accessed or modified by using the call GetPlatformControlHandle.
Adding and Removing Menu Items
There is no direct API yet to add or remove menu items but you can do it with Mac toolbox calls after accessing the native menu handle with GetPlatformMenuHandle(). If you need to create the popup menu from scratch for instance you can start with a MENU resource containing only 1 item and delete it.
AppendMenu(macMenu, "\pMy new item"); // use a pascal string
#endif
Reading Popup Menu Items
GetMenuString(Environment* ev, FW_CString& str) reads the current menu item in str.
GetMenuString(Environment* ev, short index, FW_CString& str) reads the menu item at position index (starting with 1)
Using Popup Menu Notifications
To perform an action in response to a menu item selection you need to do two things:
1) Set your control message and control receiver fields in the popup resource definition.
FW_RPopupMenu
(
...
FW_kPopupClickedMsg, // default popup message (or your own)
FW_kFrameReceiver, // frame is receiver (or FW_kViewReceiver)
...
If the popup menu is created by program the message is already set by the class constructor. You must connect the popup menu to its receiver with a line like this:
popup1->LinkControlTo(ev, frame);
2) Implement the HandleNotification method in your frame or your view and trap the FW_kPopupClickedMsg message. The notification received is an instance of FW_CPopupMenuNotification. It provides two additional APIs over its base class FW_CControlNotification: GetMenuString and GetMenuIndex.
// No need to check the view id, this frame has only 1 popup menu
// We retrieve the menu item selected
FW_CString itemString;
popupNotification.GetMenuString(ev, itemString);
...
}
break;
Remember that reselecting the current menu item doesn't trigger any notification (the control's value stays the same).
Using Scroll Bars (FW_CScrollBar)
Creation by Program or Resource
The class FW_CScrollBar implements native scroll bar controls. To create one you can either use a resource FW_RScrollBar or the constructor of FW_CScrollBar.
The class constructor takes very few arguments. When creating it by program you only need to define its bounds; you can leave the view id as 0 because it won't be used elsewhere:
The bounds rectangle vertSbRect determines if it's a vertical or horizontal scroll bar. Its width, or height, must be 16 pixels on the Macintosh to get the correct look. We recommend to use the following call to read the default size and not hard-code any platform specific value:
FW_kVScrollBarBinding, // Standard vertical SB binding
0, // control message
0, // control receiver
0, // control value
0, // SB Min Value (adjusted at runtime)
1, // SB Max Value (adjusted at runtime)
FW_ONE, // Minor Units (adjusted at runtime)
FW_ONE // Major Units (adjusted at runtime)
),
• A unique view id is required when the scroll bar is used in a scroll bar scroller, it will be repeated in the FW_RScrollBarScroller resource.
• The bounds can take advantage of the macro FW_SBSIZE. Remember also to overlap the edge of the scroll bar by one pixel with its parent view to avoid creating a thicker line.
• The view binding should be either FW_kVScrollBarBinding or FW_kHScrollBarBinding, to make the scroll bar follow the edge of its parent view when resizing occurs.
• The message and receiver fields should stay 0 unless you want the scroll bar to notify other objects when its value changes. This is separate from the FW_kScrollMsg notification that is always sent internally when the scroll bar is clicked on. The scroller object is not declared in the scroll bar receiver field, it is the other way around.
• The last four fields, min, max, minor units and major units, are not used for regular scroll bars associated with a scroller because the scroller adjusts these scroll bar parameters at runtime. You only need to enter valid values if the scroll bar is connected to another kind of object which won't adjust its parameters.
Using Scroll Bars in Scrollers
See the Engineering note "Scrolling" in the same folder. This covers also FW_CScrollNotification.
Miscellaneous Issues
Adding Colors to Controls
Macintosh controls use a white background color by default (or rather the background color of their window's grafport). Check boxes and radio buttons will come out as white rectangles over a non-white parent view. In order to make them look "transparent" you can create a color table either for the frame's window or for each control individually. Adding a background color at the window level is enough if all controls can share the same background color. If two or more colors are required you need to modify the controls themselves (do it in the PostCreateViewFromStream method, use GetPlatformControlHandle to access the Mac handle and use toolbox calls to create the color table).
Form provides an example of adding a color table to a dialog window:
